File: README.TXT
Copyright Norman Wilde 1993
/***********************************************************************/
/* The code and documentation for the "little language" based testing  */
/* system is provided free. You are welcome to duplicate it and        */
/* modify it. (However the AnaGram programming system it uses is a     */
/* commercial product, available from Jerome T. Holland, 22 Forty      */
/* Acres Drive, Wayland, MA 01778, tel. 508-358-7968.)                 */
/*                                                                     */
/* If you have any suggestions about the testing system, please let    */
/* me know.                                                            */
/*                                                                     */
/* The system is provided as-is and with no warranty of fitness for use*/
/* for any particular purpose or situation. I disclaim all             */
/* responsibility for any damages arising out of the use of this system*/
/* or any of its components.                                           */
/*                                       Norman Wilde                  */
/*                                       wilde@cs.uwf.edu              */
/***********************************************************************/

INTRODUCTION:

This readme file describes the content and the use
of a testing system for objects and other c/c++ code
based on a "little language". The objective of the system
is to let a programmer generate test driver programs that
will thoroughly test an object class or a collection of
c functions.

The overall structure
of the system is as shown in the following diagram:

       Driver Generator Language
        syntax file(DGEN.SYN)    -> AnaGram
                                       |
                                       V
             Test spec     -> Driver generator  -> Test Driver
            (Tnnn.TST)          (DGEN.EXE)          (Tnnn.CPP)

You can use the existing system immediately to build test drivers that
only use basic c data types such as strings, ints, etc. If you need to
make a driver that handles your specialized objects you need to
extend the syntax file (DGEN.SYN) and you will need the
AnaGram grammar based programming system.

USING THE EXISTING SYSTEM:

The current version of DGEN.SYN produces the driver generator
DGEN.EXE. This can handle test specification files containing
the following c data types:
                  char
                  string  (ie. char * with nul termination)
                  int
                  double
                  FILE *
as well as for the object classes in the Invoice example:
                  Item
                  Client
                  Invoice

To perform a set of tests, the steps are:
  1. Write a Test Specification File similar to T001.TST, which
  tests the objects in INVOICE.H and INVOICE.CPP. DGEN.SYN can be
  consulted for details of the little language for test specifications.
  2. Generate a test driver, say T001.CPP, using the following
  command:
        DGEN <T001.TST >T001.CPP
  3. Compile the resulting test driver and link it with the
  objects to be tested. The command will probably be something
  like:
        TCC T001.CPP INVOICE.CPP TESTGEN.CPP
  This should produce an executable called T001.EXE. Note that
  the TESTGEN.CPP file is needed since it contains utilities that
  help to generate combinations of data for testing.
  4. Run the test with a command such as:
        T001 > T001.OUT
  5. Check the test output in T001.OUT by hand or by comparison
  with previous output from the same test.

ADDING YOUR OWN OBJECT CLASSES:

To extend the little language for a new object class, just
add another alternative to the "declaration" production in
DGEN.SYN. The existing "ClientDeclaration" or "InvoiceDeclaration"
could serve as a model.

Use AnaGram to process the changed DGEN.SYN and produce a new DGEN.C
and DGEN.H. Then compile with a command similar to the following:
    TCC DGEN.C TUTILS.C
to produce a new DGEN.EXE and proceed as in the previous section. Note
that TUTILS.C is needed since it contains the code of the reduction
procedures.

FILES IN THE SYSTEM:
DGEN     SYN     Syntax of the Driver Generator Language
DGEN     C       Source for driver generator - produced by AnaGram
DGEN     H       Header for DGEN.C - produced by AnaGram
DGEN     EXE     Executable for driver generator
INVOICE  CPP     Code for the Invoice example
INVOICE  H       Header for the Invoice example
README   TXT     This file
T001     CPP     Test driver generated from spec. T001.TST
T001     TST     Test specification for the Invoice example
TESTGEN  CPP     Utility code used by generated test drivers.
TESTGEN  H       Header for TESTGEN.CPP
TUTILS   C       Utility code used in generating test drivers.
TUTILS   H       Header for TUTILS.C